<html>
<head>
	<title>Smack: Provider Architecture - Jive Software</title>
	<link rel="stylesheet" type="text/css" href="style.css" />
</head>

<body>

<div class="header">
Provider Architecture: Packet Extensions and Custom IQ's
</div>

<div class="nav">
&laquo; <a href="index.html">Table of Contents</a>
</div>

<p>
<p class="subheader">Introduction</p>

The Smack provider architecture is a system for plugging in
custom XML parsing of packet extensions and IQ packets. The 
standard  <a href="extensions/index.html">Smack Extensions</a>
are built using the provider architecture. There are two types of
providers:<ul>
      <li><tt>IQProvider</tt> -- parses IQ requests into Java objects.
      <li><tt>Extension Provider</tt> -- parses XML sub-documents attached to 
      packets into PacketExtension instances.</ul>

By default, Smack only knows how to process a few standard packets and sub-packets 
that are in a few namespaces such as:<ul>
      <li>jabber:iq:auth
      <li>jabber:iq:roster
      <li>jabber:iq:register</ul>

There are many more IQ types and extensions that are part of XMPP standards, and of
course an endless number that can be added as custom extensions.  To support this, an
extensible parsing mechanism is provided via Smack and user build providers. 
<p>
Whenever a packet extension is found in a packet, parsing will 
be passed to the correct provider. Each provider can either implement the 
PacketExtensionProvider interface or be a standard Java Bean. In the 
former case, each extension provider is responsible for parsing the raw 
XML stream, via the <a href="http://www.xmlpull.org/">XML Pull Parser</a>, to contruct an object. In the latter case, bean introspection 
is used to try to automatically set the properties of the class using 
the values in the packet extension sub-element.
<p>
When no extension provider is registered for an element name and 
namespace combination, Smack will store all top-level elements of the 
sub-packet in the DefaultPacketExtension object and then attach it to the packet.

<p>
Management of these providers is accomplished via the <a href="">ProviderManager</a> 
class.  There are multiple ways to add providers to the manager.<ul>
<li>Call addXXProvider methods - You can call the appropriate add methods directly.
<pre>
    ProviderManager.getInstance().addIQProvider("element", "namespace", new MyIQProvider());
    ProviderManager.getInstance().addExtensionProvider("element", "namespace", new MyExtProvider());
</pre>
<li>Add a loader - You can add a ProviderLoader which will inject a means of loading multiple
providers (both types) into the manager.  This is the mechanism used by Smack to load from the
Smack specific file format (via ProviderFileLoader). Implementers can provide the means to load
providers from any source they wish, or simply reuse the ProviderFileLoader to load from
their own provider files.
<pre>
    ProviderManager.getInstance().addLoader(new ProviderFileLoader(FileUtils.getStreamForUrl("classpath:com/myco/provider/myco_custom.providers", null)));
</pre> 
<li>VM Argument - You can add a provider file via the VM argument <i>smack.provider.file</i>.  
This will load the file at the specified URL during startup when Smack initializes.  
This also assumes the default configuration, since it requires that the <b>VmArgInitializer</b> was 
part of the startup configuration.

<pre>
    -Dsmack.provider.file=classpath:com/myco/provider/myco_custom.providers
    or
    -Dsmack.provider.file=file:///c:/myco/provider/myco_custom.providers
</pre> 
</ul>

<p class="subheader">IQ Providers</p>

The IQ provider class can either implement the IQProvider
interface, or extend the IQ class. In the former case, each IQProvider is 
responsible for parsing the raw XML stream to create an IQ instance. In 
the latter case, bean introspection is used to try to automatically set 
properties of the IQ instance using the values found in the IQ packet XML. 
For example, an XMPP time packet resembles the following:

<p>
<i>Introspection</i>
<p>
<u>Time Packet</u>
<pre>
    &lt;iq type='result' to='joe@example.com' from='mary@example.com' id='time_1'&gt;
        &lt;query xmlns='jabber:iq:time'&gt;
            &lt;utc&gt;20020910T17:58:35&lt;/utc&gt;
            &lt;tz&gt;MDT&lt;/tz&gt;
            &lt;display&gt;Tue Sep 10 12:58:35 2002&lt;/display&gt;
        &lt;/query&gt;
    &lt;/iq&gt;
</pre>

<p>
<u>Time IQ Class</u>
<pre>
    class Time extends IQ {
        private Date utc;
        private TimeZone timeZone;
        private String display;

        @Override
        public String getChildElementXML() {
            return null;
        }

        public void setUtc(String utcString) {
            try {
                utc = StringUtils.parseDate(utcString);
            } catch (ParseException e) {
            }
        }

        public void setTimeZone(String zone) {
            timeZone = TimeZone.getTimeZone(zone);
        }

        public void setDisplay(String timeDisplay) {
            display = timeDisplay;
        }
    }
</pre>

The introspection service will automatically try to convert the String
value from the XML into a boolean, int, long, float, double, or Class depending on the
type the IQ instance expects.

<p>
<i>IQProvider Implementation</i>
<p>
<u>Disco Items Packet</u>
<pre>
    &lt;iq type='result' from='shakespeare.lit' to='romeo@montague.net/orchard' id='items1'&gt;
       &lt;query xmlns='http://jabber.org/protocol/disco#items'&gt;
           &lt;item jid='people.shakespeare.lit' name='Directory of Characters'/&gt;
           &lt;item jid='plays.shakespeare.lit' name='Play-Specific Chatrooms'/&gt;
           &lt;item jid='mim.shakespeare.lit' name='Gateway to Marlowe IM'/&gt;
           &lt;item jid='words.shakespeare.lit' name='Shakespearean Lexicon'/&gt;
           &lt;item jid='globe.shakespeare.lit' name='Calendar of Performances'/&gt;
           &lt;item jid='headlines.shakespeare.lit' name='Latest Shakespearean News'/&gt;
           &lt;item jid='catalog.shakespeare.lit' name='Buy Shakespeare Stuff!'/&gt;
           &lt;item jid='en2fr.shakespeare.lit' name='French Translation Service'/&gt;
       &lt;/query&gt;
    &lt;/iq&gt;
</pre>

<p>
<u>Disco Items IQProvider</u>
<pre>
    public class DiscoverItemsProvider implements IQProvider {

        public IQ parseIQ(XmlPullParser parser) throws Exception {
            DiscoverItems discoverItems = new DiscoverItems();
            boolean done = false;
            DiscoverItems.Item item;
            String jid = "";
            String name = "";
            String action = "";
            String node = "";
            discoverItems.setNode(parser.getAttributeValue("", "node"));
            while (!done) {
                int eventType = parser.next();
	
                if (eventType == XmlPullParser.START_TAG && "item".equals(parser.getName())) {
                    // Initialize the variables from the parsed XML
                    jid = parser.getAttributeValue("", "jid");
                    name = parser.getAttributeValue("", "name");
                    node = parser.getAttributeValue("", "node");
                    action = parser.getAttributeValue("", "action");
                }
                else if (eventType == XmlPullParser.END_TAG && "item".equals(parser.getName())) {
                    // Create a new Item and add it to DiscoverItems.
                    item = new DiscoverItems.Item(jid);
                    item.setName(name);
                    item.setNode(node);
                    item.setAction(action);
                    discoverItems.addItem(item);
                }
                else if (eventType == XmlPullParser.END_TAG && "query".equals(parser.getName())) {
                    done = true;
                }
            }
            return discoverItems;
        }
    }
</pre>

<p class="subheader">Extension Providers</p>

Packet extension providers are responsible for parsing packet extensions, which are 
child elements in a custom namespace of IQ, message and presence packets.
<p>
<u>Pubsub Subscription Packet</u>

<pre>
   &lt;iq type='result' from='pubsub.shakespeare.lit' to='francisco@denmark.lit/barracks' id='sub1'&gt;
       &lt;pubsub xmlns='http://jabber.org/protocol/pubsub'&gt;
           &lt;subscription node='princely_musings' jid='francisco@denmark.lit' subscription='unconfigured'&gt;
               &lt;subscribe-options&gt;
                   &lt;required/&gt;
               &lt;/subscribe-options&gt;
           &lt;/subscription&gt;
       &lt;/pubsub&gt;
    &lt;/iq&gt;
</pre>

<p>
<u>Subscription PacketExtensionProvider Implementation</u>

<pre>
    public class SubscriptionProvider implements PacketExtensionProvider {
        public PacketExtension parseExtension(XmlPullParser parser) throws Exception {
            String jid = parser.getAttributeValue(null, "jid");
            String nodeId = parser.getAttributeValue(null, "node");
            String subId = parser.getAttributeValue(null, "subid");
            String state = parser.getAttributeValue(null, "subscription");
            boolean isRequired = false;

            int tag = parser.next();

            if ((tag == XmlPullParser.START_TAG) && parser.getName().equals("subscribe-options")) {
                tag = parser.next();
	
                if ((tag == XmlPullParser.START_TAG) && parser.getName().equals("required"))
                    isRequired = true;
			
                while (parser.next() != XmlPullParser.END_TAG && parser.getName() != "subscribe-options");
            }
            while (parser.getEventType() != XmlPullParser.END_TAG) parser.next();
            return new Subscription(jid, nodeId, subId, (state == null ? null : Subscription.State.valueOf(state)), isRequired);
        }
    }
</pre>

<p class="subheader">Provider file format</p>

This is the format for a provider file which can be parsed by the <b>ProviderFileLoader</b>.
<pre>
 &lt;?xml version="1.0"?&gt;
 &lt;smackProviders&gt;
     &lt;iqProvider&gt;
         &lt;elementName&gt;query&lt;/elementName&gt;
         &lt;namespace&gt;jabber:iq:time&lt;/namespace&gt;
         &lt;className&gt;org.jivesoftware.smack.packet.Time&lt/className&gt;
     &lt;/iqProvider&gt;
     
     &lt;iqProvider&gt;
         &lt;elementName&gt;query&lt;/elementName&gt;
         &lt;namespace&gt;http://jabber.org/protocol/disco#items&lt;/namespace&gt;
         &lt;className&gt;org.jivesoftware.smackx.provider.DiscoverItemsProvider&lt/className&gt;
     &lt;/iqProvider&gt;

    &lt;extensionProvider&gt;
        &lt;elementName&gt;subscription&lt;/elementName&gt;
        &lt;namespace&gt;http://jabber.org/protocol/pubsub&lt;/namespace&gt;
        &lt;className&gt;org.jivesoftware.smackx.pubsub.provider.SubscriptionProvider&lt/className&gt;
    &lt;/extensionProvider&gt;
 &lt;/smackProviders&gt;</pre>

Each provider is associated with an element name and a namespace. If multiple provider entries attempt to register to 
handle the same namespace, the last entry added to the <b>ProviderManager</b> will overwrite any other that was loaded 
before it. 
<p>

      

<br clear="all" /><br><br>

<div class="footer">
Copyright &copy; Jive Software 2002-2008
</div>

</body>
</html>
